@proton/js

protonjs

Javascript API for integration with Proton

Installation

NPM

The official distribution package can be found at npm.

NodeJS Dependency

yarn add @proton/js

Using with Typescript

If you're using Node (not a browser) then you'll also need to make sure the dom lib is referenced in your tsconfig.json:

{
	"compilerOptions": {
		"lib": [..., "dom"]
	}
}

Browser Distribution

The dist-web folder contains minified bundles ready for production, along with source mapped versions of the library for debugging.

Import

ES Modules

Importing using ES6 module syntax in the browser is supported if you have a transpiler, such as Babel.

import { Api, JsonRpc, RpcError, JsSignatureProvider } from '@proton/js';

CommonJS

Importing using commonJS syntax is supported by NodeJS out of the box.

const { Api, JsonRpc, RpcError, JsSignatureProvider } = require('@proton/js');
const fetch = require('node-fetch'); // node only; not needed in browsers

Basic Usage

Signature Provider

The Signature Provider holds private keys and is responsible for signing transactions.

Using the JsSignatureProvider in the browser is not secure and should only be used for development purposes. Use a secure vault outside of the context of the webpage to ensure security when signing transactions in production

const defaultPrivateKey = "5JtUScZK2XEp3g9gh7F8bwtPTRAkASmNrrftmx4AxDKD5K4zDnr"; // bob
const signatureProvider = new JsSignatureProvider([defaultPrivateKey]);

JSON-RPC

Open a connection to JSON-RPC, include fetch when on NodeJS.

const rpc = new JsonRpc(['http://127.0.0.1:8888'], { fetch });

Check User Verification

validKycProviders

A list of valid KYC Providers are stored here. When the JsonRpc is instantiated, it will check all the kyc providers and remove any blacklisted providers from this list.

It is an array of strings like so:

console.log(this.rpc.validKycProviders);

['metal.kyc']

isLightKYCVerified

This function serves to check a user's verification status by cross-referencing the user's KYC data against a list of valid KYC providers. A light KYC is considered verification with the user's first name, last name, address and birth date.

After instantiating the rpc, it can be called like so:

this.rpc.isLightKYCVerified(account)

The single argument account that this function takes in can accept a string account name or the user data returned from this.rpc.get_table_rows for the usersinfo table.This function returns the user data object with a flag under the key isLightKYCVerified.

API

const api = new Api({ rpc, signatureProvider });

Sending a transaction

transact() is used to sign and push transactions onto the blockchain with an optional configuration object parameter. This parameter can override the default value of broadcast: true, and can be used to fill TAPOS fields given expireSeconds and either blocksBehind or useLastIrreversible. Given no configuration options, transactions are expected to be unpacked with TAPOS fields (expiration, ref_block_num, ref_block_prefix) and will automatically be broadcast onto the chain.

(async () => {
  const result = await api.transact({
    actions: [{
      account: 'eosio.token',
      name: 'transfer',
      authorization: [{
        actor: 'useraaaaaaaa',
        permission: 'active',
      }],
      data: {
        from: 'useraaaaaaaa',
        to: 'useraaaaaaab',
        quantity: '0.0001 SYS',
        memo: '',
      },
    }]
  }, {
    blocksBehind: 3,
    expireSeconds: 30,
  });
  console.dir(result);
})();

Error handling

use RpcError for handling RPC Errors

...
try {
  const result = await api.transact({
  ...
} catch (e) {
  console.log('\nCaught exception: ' + e);
  if (e instanceof RpcError)
    console.log(JSON.stringify(e.json, null, 2));
}
...

Contributing

Contributing Guide

Code of Conduct

License

MIT